Readme improvements #597
Readme improvements #597
Conversation
I just pushed up the |
|
Just some minor inline nits, but generally looks very good :) |
|
It is probably a good idea to leave this branch accessible with no squashing of commits. It may be easier for translators to follow along commit by commit. We should still only push a single squashed commit to master, but lets leave the history here to help the translators. |
👍 |
readme.md
Outdated
|
|
||
| `.only` applies across all test files, so if you use it in one file, no tests from the other file will run. | ||
|
|
||
| ### Skip-tests |
There was a problem hiding this comment.
Need to retitle to Skipping tests to be consistent with the other titles.
Fair enough. I'll make them consistent in the other direction. Keeping spaces for JSON blocks and CLI output.
@jamestalmage script what? I used the Whitespace package in Atom which did the trick, although the right indentation varies by code block which is annoying.
Yes I was planning to squash and merge directly on Updated. Added a bunch more changes (see commits after Timing wise perhaps best to land #592 and #573 first. It's easier to update this PR so those new doc inserts read well with the rest of the changes here than it is to update them in their respective PRs. |
A way to apply a series of commits, excluding whitespace only changes. |
|
Updated with improved |
|
Had a read through and I think that looks just fine @novemberborn 👍 |
|
If @novemberborn made all requested changes, is it good to go or anyone else has some more suggestions? |
|
@vdemedes I'm waiting for #573 to land first. |
|
@novemberborn #573 was landed. Can you fix the merge conflict and squash merge this to master? |
Use fenced code blocks, if anybody got confused by the $ character in the inline code samples maybe that's clearer. Mention an approach that does not use ava --init.
The documentation uses 'directory' not 'folder'.
* Explain what directory recursion means. * Mention that node_modules directories are ignored. * Emphasize that fixtures/helpers/node_modules are always ignored. * Reword how the _ prefix is useful (the reason seemed to apply to the previous sentence as a whole).
Clarify that tests run concurrently and can be both synchronous and asynchronous, with synchronous being the default.
* Consistently use 'callback' for the function that's passed to the test methods. * Use "test title" not "test name" and improve title explanation. * Reword "context" to be the "execution object" to avoid confusion with the context that beforeEach/afterEach hooks can manipulate. * Explain the convention to name this execution object 't'. * Be clearer which non-assertion methods are available on the execution object.
* Reword the explanation * Link to tap and tape * More examples * Link back to the explanatory section in the .plan(count) docs
* Remind users that AVA runs tests concurrently. * Emphasize that serial tests are executed before concurrent ones. * Note that test files are still run concurrently unless the --serial flag is used.
* Prioritize that this should be used during development. * Explicitly mention the modifier, not just in the example. * Explain that this applies across all test files.
* Hopefully clarify the various nuances in when these hooks execute * Note that before/after hooks may not be necessary due to process isolation * Clarify that context sharing is not available to before/after hooks
* Be more specific about what modifiers are * Simplify example * Reword bit about temporarily adding .skip or .only
* Prefer 'library' over 'module' * Stipulate that the library must throw an exception * Link to the built-in assertions and assertion planning sections
* Be less apologetic * Recommend the require hook * Suggest transpiling in a separate process
* Indent the 'skipping assertions' and 'enhanced' sections * Change title for the 'enhanced' section * Remove simple example, contrast AVA with Node's default assert library
* Add to TOC * Reword Temp files section * Reword Cod ecoverage section, drop mention of .babelrc files
* tap rather than node-tap * less personal review of other test runners * reword custom reporter section * ensure the headings are questions, and the answers are phrased like answers * https link for stack overflow
* Title in line with other titles * Reword description
* Title in line with other titles * Reword description
Clarify that .plan() and .end() are on the 't' object.
* Consistent title * Reword description * Improve examples
These sections read better when combined. I've also reworded the config documentation. Changed Babel links to use HTTPS.
|
Updated. I decided to combine the ES2015 and Babel config sections, it read a lot better that way. Also reworded it a little. @spudly are you happy with my changes? See the last commit. I'll merge if people are 👍 |
|
@novemberborn Looks good. Just merge now. We can follow up later with improvements if anyone has comments. This changes a lot of things, so would be good to get it merged asap. |
|
Thanks for leveling up the docs @novemberborn :) |
|
@novemberborn, no complaints here. Looks good. |
7 participants
I was going to document watch mode but then realized I hadn't really read the README in a while. I figured I'd use my fresh set of eyes to try and improve it instead.
I've tried to document rationale for each change in the individual commits. I'll squash these into a single commit before merging. Happy to wait until some of the outstanding PRs are in to avoid those having to be rebased again.
Hopefully this version of the readme has some better examples and brings various nuances and hidden behaviors to the fore. Let me know what else I should change, or revert 😄
P.S. Apologies to the awesome translators for this massive update. You folks rock.